CIOpenFileDialog / CISaveFileDialog

CIOpenFileDialog wraps the IFileOpenDialog interface. Extends the IFileDialog interface by adding methods specific to the open dialog.

CIOpenFileDialog wraps the IFileSaveDialog interface. Extends the IFileDialog interface by adding methods specific to the save dialog, which include those that provide support for the collection of metadata to be persisted with the file.

Both also wrap the IFileDialogEvents interface, which exposes methods that allow notification of events within a common file dialog, and the IFileDialogCustomize interface, which exposes methods that allow an application to add controls to a common file dialog.

Include file: AfxNova/CIOpenSaveFile.inc

Constructors (CIOpenFileDialog/CISaveFileDialog)

Usage

DIM pofd AS CIOpenFileDialog
DIM psfd AS CISaveFileDialog

Examples

Open File Dialog:

#define _WIN32_WINNT &h0602
#include once "AfxNova/CWindow.inc"
#include once "AfxNova/CIOpenSaveFile.inc"
#include once "AfxNova/CIFileDialogEvents.inc"
USING AfxNova

DIM pofd AS CIOpenFileDialog
' // Set the file types
pofd.AddFileType("FB code files", "*.bas;*.inc;*.bi")
pofd.AddFileType("Executable files", "*.exe;*.dll")
pofd.AddFileType("All files", "*.*")
pofd.SetFileTypes()
' // Multiple selection (default is single selection)
DIM options AS FILEOPENDIALOGOPTIONS = pofd.GetOptions
pofd.SetOptions(options OR FOS_ALLOWMULTISELECT)
' // Optional: Set the title of the dialog
'   pofd.SetTitle("A Single-Selection Dialog")
' // Set the folder
pofd.SetFolder(CURDIR)
pofd.SetDefaultExtension("bas")
pofd.SetFileTypeIndex(1)

' // Set events
DIM pfde AS ANY PTR = NEW CIFileDialogEvents
pofd.SetEvents(pfde)

' // Display the dialog
' // change hwnd for your parent window
DIM hr AS HRESULT = pofd.ShowOpen(hwnd)

' // Folder name
print "Folder name: ";  pofd.GetFolder

' *** Single selection ***
' // Get the result
IF hr = S_OK THEN
   print pofd.GetResultString
END IF

' *** Multiple selection ***
DIM dwsRes AS DWSTRING = pofd.GetResultsString
FOR i AS LONG = 1 TO pofd.GetResultsCount
   PRINT pofd.ParseResults(dwsRes, i)
NEXT

Save File Dialog:

#define _WIN32_WINNT &h0602
#include once "AfxNova/CWindow.inc"
#include once "AfxNova/CIOpenSaveFile.inc"
#include once "AfxNova/CIFileDialogEvents.inc"
USING AfxNova

DIM psfd AS CISaveFileDialog
' // Set the file types
psfd.AddFileType("FB code files", "*.bas;*.inc;*.bi")
psfd.AddFileType("Executable files", "*.exe;*.dll")
psfd.AddFileType("All files", "*.*")
psfd.SetFileTypes()
' // Optional: Set the title of the dialog
'   psfd.SetTitle("Save File Dialog")
' // Set the folder
psfd.SetFolder(CURDIR)
psfd.SetDefaultExtension("bas")
psfd.SetFileTypeIndex(1)

' // Set events
DIM pfde AS ANY PTR = NEW CIFileDialogEvents
psfd.SetEvents(pfde)

' // Display the dialog
' // change hwnd for your parent window
DIM hr AS HRESULT = psfd.ShowSave(hwnd)

' // Folder name
print "Folder name: ";  psfd.GetFolder

' // Get the result
IF hr = S_OK THEN
   print psfd.GetResultString
END IF

Methods of the CIOpenFileDialog and CISaveFileDialog classes

Common methods inherited from IFileDialog

Common methods from IFileDialog2

Additional methods of the CISaveFileDialog class

AddFileType

Adds a file type and pattern to the table.

FUNCTION AddFileType (BYVAL pwszName AS WSTRING PTR, BYVAL pwszSpec AS WSTRING PTR)

Usage example:

DIM pofd AS CIOpenFileDialog = CIOpenFileDialog(50, 50)
// Set the file types
pofd.AddFileType("FB code files", "*.bas;*.inc;*.bi")
pofd.AddFileType("Executable files", "*.exe;*.dll")
pofd.AddFileType("All files", "*.*")
pofd.SetFileTypes()

GetPtr

Returns the underlying IFileOpenDialog interface pointer.

FUNCTION CISaveFileDialog.GetPtr () AS IFileSaveDialog PTR

Remarks

Don’t release the returned pointer.

GetIFileDialogPtr

Returns the underlying IFileDialog interface pointer.

FUNCTION CISaveFileDialog.GetIFileDialogPtr () AS IFileDialog PTR

Remarks

The returned pointer must be released with the Release method of the IFileDialog interface when no longer needed.

SetEvents

Assigns an event handler that listens for events coming from the dialog.

FUNCTION SetEvents (BYVAL pfde as IFileDialogEvents PTR) AS DWORD

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

ShowOpem

Displays the Open File Dialog.

FUNCTION ShowOpen (BYVAL hwndOwner AS HWND) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

ShowSave

Displays the Save File Dialog.

FUNCTION ShowSave (BYVAL hwndOwner AS HWND) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

AddPlace

Adds a folder to the list of places available for the user to open or save items.

FUNCTION AddPlace (BYVAL psi AS IShellItem PTR, BYVAL fdap AS FDAP) AS HRESULT

FDAP enumeration

Advise

Assigns an event handler that listens for events coming from the dialog.

FUNCTION Advise (BYVAL pfde as IFileDialogEvents PTR) AS DWORD

Return value

A value identifying this event handler. When the client is finished with the dialog, that client must call the Unadvise method with this value.

ClearClientData

Instructs the dialog to clear all persisted state information.

FUNCTION ClearClientData () AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Persisted information can be associated with an application or a GUID. If a GUID was set by using IFileDialog::SetClientGuid, that GUID is used to clear persisted information.

Close

Closes the dialog.

FUNCTION Close (BYVAL hr AS HRESULT) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

An application can call this method from a callback method or function while the dialog is open. The dialog will close and the Show method will return with the HRESULT specified in hr.

If this method is called, there is no result available for the GetResult or GetResults methods, and they will fail if called.

GetCurrentSelection

Gets the folder used as a default if there is not a recently used folder value available.

FUNCTION GetCurrentSelection (BYVAL sigdnName AS SIGDN = SIGDN_NORMALDISPLAY) AS DWSTRING

SIGDN Enumeration

Return value

The folder name.

GetFileName

Retrieves the text currently entered in the dialog’s File name edit box.

FUNCTION GetFileName () AS DWSTRING

Return value

The folder name.

Remarks

The text in the File name edit box does not necessarily reflect the item the user chose. To get the item the user chose, use GetResult or GetResultString.

GetFileTypeIndex

Gets the file type that appears as selected in the dialog.

FUNCTION GetFileTypeIndex () AS UINT

Return value

Gets the currently selected file type.

Remarks

The index of the selected file type in the file type array passed to SetFileTypes in its cFileTypes parameter.

Note This is a one-based index rather than zero-based.

GetFolder

Gets either the folder currently selected in the dialog, or, if the dialog is not currently displayed, the folder that is to be selected when the dialog is opened.

FUNCTION GetFolder (BYVAL sigdnName AS SIGDN = SIGDN_NORMALDISPLAY) AS DWSTRING

SIGDN Enumeration

Return value

The folder name.

GetOptions

Gets the current flags that are set to control dialog behavior.

FUNCTION GetOptions () AS FILEOPENDIALOGOPTIONS

Return value

A value made up of one or more of the FILEOPENDIALOGOPTIONS values.

GetResult

Gets the choice that the user made in the dialog.

FUNCTION GetResult () AS IShellItem PTR

Return value

A pointer to an IShellItem that represents the user’s choice.

GetResultString

Gets the choice that the user made in the dialog.

FUNCTION GetResultString (BYVAL sigdnName AS SIGDN = SIGDN_NORMALDISPLAY) AS DWSTRING

SIGDN Enumeration

Return value

The choice that the user made in the dialog.

SetClientGuid

Enables a calling application to associate a GUID with a dialog’s persisted state.

FUNCTION SetClientGuid (BYVAL guid AS GUID PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

A dialog’s state can include factors such as the last visited folder and the position and size of the dialog.

Typically, this state is persisted based on the name of the executable file. By specifying a GUID, an application can have different persisted states for different versions of the dialog within the same application (for example, an import dialog and an open dialog).

SetClientGuid should be called immediately after creation of the dialog object.

SetDefaultExtension

Sets the default extension to be added to file names.

FUNCTION SetDefaultExtension (BYVAL pwszDefaultExtension AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

If this method is called before showing the dialog, the dialog will update the default extension automatically when the user chooses a new file type (see SetFileTypes).

SetDefaultFolder

Sets the folder used as a default if there is not a recently used folder value available.

FUNCTION SetDefaultFolder (BYVAL psi AS IShellItem PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetFileName

Sets the file name that appears in the File name edit box when that dialog box is opened.

FUNCTION SetFileName (BYVAL pwszName AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetFileNameLabel

Sets the file name that appears in the File name edit box when that dialog box is opened.

FUNCTION SetFileNameLabel (BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetFileTypeIndex

Sets the file type that appears as selected in the dialog.

FUNCTION SetFileTypeIndex (BYVAL iFileType AS UINT) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetFileTypes

Sets the file types that the dialog can open or save.

FUNCTION SetFileTypes (BYVAL cFileTypes AS UINT, BYVAL rgFilterSpec AS COMDLG_FILTERSPEC PTR) AS HRESULT

Return value

If the method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code, including the following:

SetFolder

Sets a folder that is always selected when the dialog is opened, regardless of previous user action.

FUNCTION SetFolder (BYVAL pwszFolderName AS WSTRING PTR) AS HRESULT

Return value

If the method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code, including the following:

Remarks

This folder overrides any “most recently used” folder. If this method is called while the dialog is displayed, it causes the dialog to navigate to the specified folder.

In general, we do not recommended the use of this method. If you call SetFolder before you display the dialog box, the most recent location that the user saved to or opened from is not shown. Unless there is a very specific reason for this behavior, it is not a good or expected user experience and should therefore be avoided. In almost all instances, SetDefaultFolder is the better method.

As of Windows 7, if the path of the folder specified through psi is the default path of a known folder, the known folder’s current path is used in the dialog. That path might not be the same as the path specified in psi; for instance, if the known folder has been redirected. If the known folder is a library (virtual folders Documents, Music, Pictures, and Videos), the library’s path is used in the dialog. If the specified library is hidden (as they are by default as of Windows 8.1), the library’s default save location is used in the dialog, such as the Microsoft OneDrive Documents folder for the Documents library. Because of these mappings, the folder location used in the dialog might not be exactly as you specified when you called this method.

SetOkButtonLabel

Sets the text of the Open or Save button.

FUNCTION SetOkButtonLabel (BYVAL pwszText AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetOptions

Sets the current flags that are set to control dialog behavior.

FUNCTION SetOptions (BYVAL fos AS FILEOPENDIALOGOPTIONS) AS HRESULT

SetTitle

Sets the title of the dialog.

FUNCTION SetTitle (BYVAL pwszTitle AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Unadvise

Removes an event handler that was attached through the Advise method.

FUNCTION Unadvise BYVAL dwCookie AS DWORD() AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

ApplyProperties

Applies a set of properties to an item using the Shell’s copy engine.

FUNCTION ApplyProperties (BYVAL psi AS IShellItem PTR, BYVAL pStore AS IPropertyStore PTR, _
   BYVAL hWnd AS HWND, BYVAL pSink AS IFileOperationProgressSink PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

GetProperties

Retrieves the set of property values for a saved item or an item in the process of being saved.

FUNCTION GetProperties (BYVAL ppStore AS IPropertyStore PTR PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetCollectedProperties

Specifies which properties will be collected in the save dialog.

FUNCTION SetCollectedProperties (BYVAL pList AS IPropertyDescriptionList PTR, _
   BYVAL fAppendDefault AS WINBOOL) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The calling application can use the PSGetPropertyDescriptionListFromString function to construct an IPropertyDescriptionList from a string such as “prop:Comments;Subject;”.

For more information about property schemas, see ]Property Schemas](https://learn.microsoft.com/en-us/windows/win32/properties/building-property-handlers-property-schemas).

SetCollectedProperties can be called at any time before the dialog is displayed or while it is visible. If different properties are to be collected depending on the chosen filetype, then SetCollectedProperties can be called in response to OnTypeChange.

Note By default, no properties are collected in the save dialog.

SetProperties

Provides a property store that defines the default values to be used for the item being saved.

FUNCTION SetProperties (BYVAL pStore AS IPropertyStore PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method can be called at any time before the dialog is opened or while the dialog is showing. If an item has inherent properties, this method should be called with those properties before showing the dialog.

When using Save As, the application should provide the properties of the item being saved to the Save dialog. Those properties should be retrieved from the original item by calling GetPropertyStore with the GPS_HANDLERPROPERTIESONLY flag.

To retrieve the properties of the saved item (which may have been modified by the user) after the dialog closes, call GetProperties.

To turn on property collection and indicate which properties should be displayed in the Save dialog, use SetCollectedProperties.

SetSaveAsItem

Sets an item to be used as the initial entry in a Save As dialog.

FUNCTION SetSaveAsItem (BYVAL psi AS IShellItem PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The name of the item is displayed in the file name edit box, and the containing folder is opened in the view. This would generally be used when the application is saving an item that already exists. For new items, use SetFileName.

SetCancelButtonLabel

Replaces the default text “Cancel” on the common file dialog’s Cancel button.

FUNCTION SetCancelButtonLabel (BYVAL pwszLabel AS LPCWSTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Changing the text on the Cancel button can be useful for situations where the OnFileOk method is used to accumulate items, and the button text should be Done instead of Cancel, for example.

SetNavigationRoot

Specifies a top-level location from which to begin browsing a namespace, for instance in the Save dialog’s Browse folder option. Users cannot navigate above this location.

FUNCTION SetNavigationRoot (BYVAL psi AS IShellItem PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

SetNavigationRoot can be used by applications that want to restrict navigation to a certain area of the Shell namespace. Items in the navigation pane are replaced with the supplied item, to guide the user from navigating outside of this part of the namespace.

This method cannot be called while the dialog is being displayed.